feat(doctor): add comprehensive checks for v2.0+ features #79

ojowwalker77 · 2026-01-17T19:03:44Z

Summary

Add diagnostic checks for all v2.0+ Matrix features
Include auto-fix capabilities where possible
Enhanced issue template with categorized checks

New Diagnostic Checks

Feature	Check	Auto-fixable
Background Jobs	Table existence, orphaned job cleanup	Yes
Hook Executions	Session tracking table	Yes
Skills Directory	Existence and skill count	Yes
Subagent Hooks	toolSearch config validation	Yes
Model Delegation	delegation config section	Yes
Dreamer Scheduler	Tables and platform registration	Yes
File Suggestion	Script installation and settings.json	Yes

Features Audited

Background job system (job tables, async operations)
One-time hook execution (hook_executions table, session tracking)
Skills migration (skills/ directory, hot-reload)
Subagent hooks (SubagentStart, SubagentStop hooks config)
Model delegation config (delegation section in config)
Config auto-upgrade (missing sections detection) - already covered
Dreamer scheduler (dreamer_tasks, dreamer_executions tables, launchd/crontab registration)
Index tools accessibility (repoPath queries) - covered via Code Index check
File suggestion auto-install (~/.claude/file-suggestion.sh)

Test plan

Build passes (bun run build)
All tests pass (bun test)
Run /matrix:doctor to verify new checks work
Test auto-fix by temporarily removing a feature

Add diagnostic checks for new Matrix features: - Background Jobs: table existence, orphaned job cleanup - Hook Executions: session tracking table - Skills Directory: existence and skill count - Subagent Hooks: toolSearch config validation - Model Delegation: delegation config section - Dreamer Scheduler: tables and platform registration - File Suggestion: script installation and settings.json All checks include auto-fix capabilities where possible. Enhanced issue template with categorized checks and table summary.

greptile-apps · 2026-01-17T19:06:40Z

Greptile Summary

This PR significantly enhances the Matrix diagnostic tool by adding comprehensive health checks for all v2.0+ and v2.1+ features, with intelligent auto-fix capabilities.

Key additions:

Background Jobs System (v2.0+): Checks for background_jobs table existence and detects/cleans up orphaned running jobs that remain from crashed processes
Hook Executions (v2.0+): Validates hook_executions table for one-time hook session tracking
Skills Directory (v2.0+): Verifies ~/.claude/skills directory exists and counts installed skills
Subagent Hooks (v2.0+): Validates toolSearch config section with preferMatrixIndex and preferContext7 preferences
Model Delegation (v2.0+): Checks delegation config section with enabled flag and model preference
Dreamer Scheduler (v2.1+): Validates dreamer_tasks and dreamer_executions tables, counts enabled tasks, and checks platform-specific scheduler registration (launchd on macOS, crontab on Linux)
File Suggestion Script (v2.0+): Verifies installation of file-suggestion.sh script, checks settings.json configuration, and validates prerequisites (rg, fzf, jq)

Auto-fix capabilities: Most issues are auto-fixable through migrations, directory creation, or config merging with defaults. The enhanced issue template now categorizes checks (core, database, hooks, config, features) for better bug reporting.

Code quality: The implementation follows existing patterns, properly handles errors, and includes detailed comments. The checks are well-organized by category and version.

Confidence Score: 4/5

This PR is safe to merge with minimal risk
The PR adds comprehensive diagnostic checks following established patterns in the codebase. One potential logic issue identified with the jq command in the file-suggestion script, though this may be pre-existing if Claude Code pipes JSON via stdin. The implementation is defensive with proper error handling, uses existing database and config utilities correctly, and includes detailed documentation. Auto-fix logic is conservative and preserves user data.
Verify that the jq command in FILE_SUGGESTION_SCRIPT (line 48) correctly receives JSON input from Claude Code's file suggestion mechanism

Important Files Changed

Filename	Overview
src/tools/doctor.ts	Added comprehensive diagnostic checks for v2.0+ features including background jobs, hook executions, skills, subagent hooks, model delegation, Dreamer scheduler, and file suggestion script with auto-fix capabilities

Sequence Diagram

sequenceDiagram
    participant User
    participant Doctor as matrixDoctor()
    participant Check as Check Functions
    participant DB as Database
    participant FS as File System
    participant Config as Config System
    participant Fix as attemptFix()

    User->>Doctor: Call /matrix:doctor
    
    Note over Doctor: Run all diagnostic checks
    
    Doctor->>Check: checkMatrixDir()
    Check->>FS: Verify ~/.claude/matrix exists
    FS-->>Check: Status
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkDatabase()
    Check->>DB: Query schema version & health
    DB-->>Check: Version & status
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkBackgroundJobs()
    Check->>DB: Check background_jobs table
    Check->>DB: Query orphaned jobs
    DB-->>Check: Table status & orphan count
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkHookExecutions()
    Check->>DB: Check hook_executions table
    DB-->>Check: Table status
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkSkillsDirectory()
    Check->>FS: Verify ~/.claude/skills exists
    Check->>FS: Count skill directories
    FS-->>Check: Directory status & count
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkSubagentHooks()
    Check->>Config: Verify toolSearch config
    Config-->>Check: Config status
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkDelegation()
    Check->>Config: Verify delegation config
    Config-->>Check: Config status
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkDreamer()
    Check->>DB: Check dreamer_tasks table
    Check->>DB: Check dreamer_executions table
    Check->>DB: Count enabled tasks
    Check->>FS: Verify platform scheduler (launchd/crontab)
    FS-->>Check: Scheduler status
    DB-->>Check: Table & task status
    Check-->>Doctor: DiagnosticCheck
    
    Doctor->>Check: checkFileSuggestion()
    Check->>FS: Check file-suggestion.sh exists
    Check->>FS: Check settings.json config
    Check->>FS: Verify prerequisites (rg, fzf, jq)
    FS-->>Check: Script & config status
    Check-->>Doctor: DiagnosticCheck
    
    Note over Doctor: Auto-fix if enabled
    
    loop For each check with issues
        Doctor->>Fix: attemptFix(check)
        
        alt Background Jobs - orphaned
            Fix->>DB: UPDATE background_jobs SET status='failed'
            DB-->>Fix: Updated
        
        else Missing database tables
            Fix->>DB: runMigrations()
            DB-->>Fix: Tables created
        
        else Skills Directory missing
            Fix->>FS: mkdirSync(SKILLS_DIR)
            FS-->>Fix: Created
        
        else Config sections missing
            Fix->>Config: Merge with DEFAULT_CONFIG
            Fix->>Config: saveConfig()
            Config-->>Fix: Saved
        
        else File Suggestion missing
            Fix->>FS: Write file-suggestion.sh script
            Fix->>FS: Update settings.json
            FS-->>Fix: Installed
        end
        
        Fix-->>Doctor: Fixed check
    end
    
    Doctor->>Doctor: Generate issue template if unfixable issues
    Doctor-->>User: DoctorResult with checks, fixes, and suggestions

greptile-apps

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

src/tools/doctor.ts

github-actions · 2026-01-18T02:38:50Z

Version files synced to 2.1.3 from CHANGELOG.md

ojowwalker77

jq reads from stdin by default - Claude Code pipes JSON to the script's stdin. No fix needed here.

greptile-apps bot reviewed Jan 17, 2026

View reviewed changes

src/tools/doctor.ts Show resolved Hide resolved

chore: add v2.1.3 changelog entry for doctor improvements

a8c01b8

chore: sync versions to 2.1.3

0c39652

ojowwalker77 commented Jan 18, 2026

View reviewed changes

Merge branch 'main' into feat/doctor-comprehensive-checks

5746d37

ojowwalker77 merged commit 68a4627 into main Jan 18, 2026
6 checks passed

ojowwalker77 deleted the feat/doctor-comprehensive-checks branch January 18, 2026 20:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(doctor): add comprehensive checks for v2.0+ features #79

feat(doctor): add comprehensive checks for v2.0+ features #79

Uh oh!

ojowwalker77 commented Jan 17, 2026

Uh oh!

greptile-apps bot commented Jan 17, 2026

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

github-actions bot commented Jan 18, 2026

Uh oh!

ojowwalker77 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

feat(doctor): add comprehensive checks for v2.0+ features #79

feat(doctor): add comprehensive checks for v2.0+ features #79

Uh oh!

Conversation

ojowwalker77 commented Jan 17, 2026

Summary

New Diagnostic Checks

Features Audited

Test plan

Uh oh!

greptile-apps bot commented Jan 17, 2026

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Jan 18, 2026

Uh oh!

ojowwalker77 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants